.\" @(#)ccal.1
.TH ccal 1 "25 July 2008"
.SH NAME
ccal \- display a calendar together with Chinese calendar
.SH SYNOPSIS
\f3ccal\f1
[
.B \-p|\-t|\-x
] [
.B \-g|\-b
] [
.B \-u
] [ [
.I month
]
.I year
]
.SH DESCRIPTION
.IX "ccal" "" "\fLcal\fP \(em display a calendar"
.IX "calendar" "display" "" "display \(em \fLcal\fP"
The
.B ccal
utility writes a Gregorian calendar together with Chinese calendar
to standard output.
If the
.I year
operand is specified, a calendar for that year is written.
If no operands are specified, a calendar for the current month is written.
By default, ASCII mode is used for the output.
.SH OPTIONS
.TP
.B \-p
Generates Encapsulated PostScript output which can be redirected into a
file. Although the file can be directly printed, the intention is to
have it embedded in other documents to make do-it-yourself calendars.
.TP
.B \-t
Generates HTML table output which can be redirected into a file to be
viewed by a web browser or customized to be part of a web page. To view
such a page, a properly installed Chinese font is required.
.TP
.B \-x
Generates XML output which can be redirected into a file to be
processed by XSLT or XSL-FO processor to generate calendars with
custom appearance. Assumes UTF-8 encoding.
.TP
.B \-g
Outputs simplified Chinese characters. Defaults to GB encoding in
character or HTML modes.
This is the default if either
.B \-p
,
.B \-t
or
.B \-x
option is selected.
.TP
.B \-b
Outputs traditional Chinese characters. Defaults to big5 encoding in
character or HTML modes.
.TP
.B \-u
Outputs Chinese characters in UTF-8 encoding rathern than GB or big5.
No effect in Encapsulated PostScript mode.
.SH OPERANDS
The following operands are supported:
.TP 8
.I month
Specify the month to be displayed, represented as a decimal integer from
.B 1
(January) to
.B 12
(December).
The default is the current month.
.TP
.I year
Specify the year for which the calendar is displayed,
represented as a decimal integer from
.B 1645
to
.BR 7000 .
However, accuracy will gradually decrease beyond 300 years
from Year 2000.  The default is the current year.
.SH "EXIT STATUS"
The following exit values are returned:
.PD 0
.TP 10
.B 0
Successful completion.
.TP
.B >0
An error occurred.
.PD
.SH "SEE ALSO"
.BR cal (1)
.SH NOTES
The marking of lunar month(s) in month header refers to new lunar
month(s) to start in that month unless there is no new lunar month
in that calendar month in which case the marking refers to the current
running lunar month. This special case will only happen occasionally
in February. To reduce the confusion on to which lunar month a day
belongs, the month header also shows the starting date(s) of any new
lunar month(s) in the calendar month.
.LP
In the default ASCII mode, a letter "R" before the lunar month number in month
header indicates that the lunar month is a leap ("run") month. The letter
after that number shows whether the lunar month is a long ("da") month, with
"D", or a short ("xiao") month, with "X". The starting date of that new lunar
month will follow after a space and begins with "S", e.g. "S26" means
this new lunar month starts on 26th of the calendar month. Inside the actual
calendar, a letter "Y" indicates the starting of the numbered lunar month.  
An additional "R" indicates that lunar month is a leap month.
solar terms ("jieqi") are coded with initials of the pinyin of
each character.
.LP
Chinese characters are used directly if options
.B \-g
,
.B \-b
or
.B \-u
are used or in PostScript, XML
or HTML modes. Should a solar term and a new lunar month fall
on the same day, the marking of the new lunar month is moved
to the next day for character modes. In the other modes, new lunar
month and solar term are marked together in that order.
.LP
The Chinese calendar was last reformed in 1645. The
current algorithm is based on the true motions of the
sun and the moon. The mean sun and/or moon motions were
used before that.
.LP
The algorithm to compute the motion of the sun is adapted
from the NOVAS-C package from the U.S. Naval Observatory.
http://aa.usno.navy.mil/AA/software/novas/novas_info.html
.LP
The algorithm to compute the motion of the moon is from the
Lunar Outreach Services which is in turn based on Meeus.
http://www.lunaroutreach.org/phases/phases.cgi (no longer available)
.LP
In Year 2033, a very rare leap 11th month will be added in December.
Due to less accurate algorithms, people used to think that the leap
month should be added after the 7th month before early
1990s. To see this calendar, type:
.RS
\f3ccal 12 2033\f1
.RE
